@openpresentation/opf 0.12.2 → 0.14.0

package/README.md

@@ -35,7 +35,7 @@ import {
   tones,
   catalogs,
   validate,
-  validatePresentation,
+  validateCatalogRecord,
 } from "@openpresentation/opf";
 
 import type { Presentation } from "@openpresentation/opf";
@@ -46,8 +46,8 @@ const deck: Presentation = {
 };
 
 console.log(presentation.$id);
-console.log(validatePresentation(deck).valid);
-console.log(validate(tones[0], "tones").valid);
+console.log(validate(deck).valid);
+console.log(validateCatalogRecord("tones", tones[0]).valid);
 console.log(audiences.map((audience) => audience.id));
 console.log(Object.keys(catalogs));
 ```
@@ -58,7 +58,7 @@ Use focused imports when you only need one surface:
 import { presentation, audience } from "@openpresentation/opf/schemas";
 import { audiences, tones } from "@openpresentation/opf/catalogs";
 import { specFileEntries } from "@openpresentation/opf/spec-files";
-import { validate, assertValid } from "@openpresentation/opf/validator";
+import { validate, assertValid, validationRules } from "@openpresentation/opf/validator";
 import {
   layoutPreviews,
   getLayoutPreview,
@@ -67,7 +67,13 @@ import {
 import type { Presentation, Audience, Tone } from "@openpresentation/opf/types";
 ```
 
-The root entry exports every schema, catalog, and validation helper for convenience. Prefer the focused subpaths above when a package consumer only needs one surface, so the root bundle's full catalog/schema payload is not loaded unnecessarily.
+The root entry holds the application-level API: schemas, catalogs, validation, variables, pagination, data helpers, font policy, `stats` and `resolveSlideContext`. Prefer the focused subpaths above when a package consumer only needs one surface, so the root bundle's full catalog/schema payload is not loaded unnecessarily.
+
+The layout engine's names are not on the root. `composeSlide`, `fitText`, `layoutQuote` and the other `layoutX`/`fitX` functions, numbering, footnotes and citations, colour contrast, code syntax, pattern fills, metric trends, chart options, script fonts and text direction come from `@openpresentation/opf/composition`; the symbol-font tables come from `@openpresentation/opf/symbol-font-encodings`.
+
+### Facts, slide context and the fonts handle
+
+`stats(presentation, options?)` reports neutral facts about a deck (structure, words, notes, images, charts, tables, datasets, citations, variables, assets, fonts) without composing, measuring or validating; see [the stats guide](../../docs/stats.md). `resolveSlideContext(presentation, index, { fonts })` resolves one slide's canvas, layout, theme and font families (slide design, then deck design, then theme, then the default font scheme) into the `ComposeSlideOptions` that `composeSlide` takes, with `unresolved-font-scheme`, `unresolved-layout` and `unresolved-theme` diagnostics. Deck-level verbs take `{ fonts }`, a handle whose `textMeasurement` is how wide the host's real fonts draw text (`paginate(deck, { fonts })`); the renderer's font loader returns a richer handle that extends it. `composeSlide` itself is engine-level and takes `textMeasurement` and `fontFamilies` (`{ heading, body, code, accent? }`) directly.
 
 ### Content conversions
 
@@ -75,21 +81,19 @@ The root entry exports every schema, catalog, and validation helper for convenie
 
 ### Markdown and outlines
 
-`@openpresentation/opf/markdown` reads and writes a deck as Markdown in a small documented dialect (YAML front matter, `---` between slides, `#` title, `##` subtitle, lists, quotes, tables, images, `chart`, `metric` and `timeline` fences, `Note:` speaker notes). `markdownToOpf(markdown, { split, defaults, validate })` returns `{ document, valid, diagnostics, counts }` with lint-shaped diagnostics that carry the line and column of the Markdown; `opfToMarkdown(document, { unsupported })` writes any valid deck, embedding what the dialect has no syntax for as YAML (or dropping it into `report.loss`), and the Markdown it writes converts back to the same deck. Deterministic and offline. Reads front matter with the `yaml` package. See the [Markdown guide](../../docs/markdown.md). Not in releases before the one that lists it in the changelog.
-
-### Design and accessibility audit
+`@openpresentation/opf/markdown` reads and writes a deck as Markdown in a small documented dialect (YAML front matter, `---` between slides, `#` title, `##` subtitle, lists, quotes, tables, images, `chart`, `metric` and `timeline` fences, `Note:` speaker notes). `fromMarkdown(markdown, { split, defaults, validate })` returns `{ presentation, valid, findings, counts }` with findings (the shared `Finding` format) that carry the line and column of the Markdown; `toMarkdown(presentation, { unsupported })` writes any valid deck, embedding what the dialect has no syntax for as YAML (or dropping it into `report.loss`), and the Markdown it writes converts back to the same deck. Deterministic and offline. Reads front matter with the `yaml` package. See the [Markdown guide](../../docs/markdown.md). Not in releases before the one that lists it in the changelog.
 
-`@openpresentation/opf/audit` exports `auditPresentation(document, options)`, `auditSource(source, options)` and `auditRules`: contrast, overflow, type size, alt text, reading order, fonts, links, charts and more, with stable `audit/<rule>` ids in lint's report shape. Read-only and deterministic; see [the audit guide](../../docs/audit.md).
+### OPF as YAML
 
-### Contextual lint (0.10.0)
+`@openpresentation/opf/yaml` reads and writes a deck as YAML, the authoring form of the same data (JSON stays canonical). `fromYaml(text, { aliases, validate })` reads strict JSON-compatible YAML 1.2 (one document, a mapping at the root, no custom tags, duplicate keys or non-finite numbers; anchors, aliases and merge keys only with `aliases: true`) and returns `{ presentation, valid, findings, counts, schemaValid, checks }`: the `validate` report of the deck, with every finding (the shared `Finding` format, YAML syntax errors as `yaml/<rule>` findings) located at the line and column of the YAML. `toYaml(presentation, { schemaComment })` writes canonical YAML (schema key order, block style, ambiguous strings quoted) that reads back to the same deck, and throws `OPFYamlError` for an invalid one. `parseYamlData` and `scanYamlComments` are the helpers. See [the YAML guide](../../docs/yaml.md).
 
-Version 0.10.0 adds `lintSource(source, options)` and `lintPresentation(document, options)` from `@openpresentation/opf/lint` and the root API. They report strict JSON syntax, duplicate keys, schema constraints, local catalog alternatives, asset registry errors, and explicit host contracts. Source diagnostics retain original UTF-16 ranges without rewriting the document. Options accept already loaded `catalogs` and `contracts`; no remote resources are fetched.
+### Validate (0.14.0)
 
-Earlier versions do not include these APIs. See the [lint guide](../../docs/lint.md) for configuration and the source CLI. Passing lint does not certify layout, fonts, or native export fidelity.
+`validate(input, options?)` is the one checker, from the root and from `@openpresentation/opf/validator`. `input` is a parsed presentation or strict JSON text; the result is a `ValidationReport` whose `findings` (the shared `Finding` format, `spec/schemas/finding.schema.json`) each have a stable `opf/<rule>` id, a severity and one of six categories: `format` (JSON syntax, duplicate keys, schema), `references` (catalog ids, assets, citations, datasets), `policy` (host `contracts`), `accessibility` (contrast, alt text, reading order, links), `layout` (overflow, type size, image resolution, fonts) and `content` (placeholders, empty slides, non-numeric chart cells). `valid` means no finding has severity `error`, which by default only `format`, `references` and `policy` findings can have. Text input adds line and column; `only`, `ignore` and `severity` pick and promote rules or categories; composition is lazy, so `validate(deck, { only: ["format"] })` costs what a schema check costs. Read-only and deterministic: no remote resources are fetched. See [the validate guide](../../docs/validate.md). A clean report does not certify layout, fonts, or native export fidelity.
 
 ### Patch, diff, merge and format (0.12.0)
 
-Added in 0.12.0 (not in 0.11.4 or earlier): `@openpresentation/opf/patch` is the one RFC 6902 implementation the CLI and the editor share (`applyPatch`, `applyPatchWithInverse`, `invertPatch`, strict pointer helpers, optional schema validation of the result); `@openpresentation/opf/diff` has `diffPresentations` (slide matching by id, content and similarity, moves, a readable report and a JSON Patch) and `mergePresentations` (three-way merge with conflict objects that never drop a side); `@openpresentation/opf/format` has `formatPresentation` (canonical key order and layout, idempotent). See [the guide](../../docs/patch-diff-merge-format.md).
+Added in 0.12.0 (not in 0.11.4 or earlier): `@openpresentation/opf/patch` is the one RFC 6902 implementation the CLI and the editor share (`applyPatch`, `applyPatchWithInverse`, `invertPatch`, strict pointer helpers, optional schema validation of the result); `@openpresentation/opf/diff` has `diff` (slide matching by id, content and similarity, moves, a readable report and a JSON Patch) and `merge` (three-way merge with conflict objects that never drop a side); `@openpresentation/opf/format` has `format` (canonical key order and layout, idempotent). See [the guide](../../docs/patch-diff-merge-format.md).
 
 ### Layout previews
 
@@ -173,17 +177,18 @@ import { repoReadme } from "@openpresentation/opf/repo-readme";
 console.log(repoReadme.split("\n").slice(0, 3).join("\n"));
 ```
 
-Validation results carry `errors` (structural problems that make `valid`
-false) and `warnings` (advisory issues such as unknown catalog ids in
-`narrative`, `design`, or chart `type` references — these never affect
-`valid`). Documents that declare matching inline `catalogs.<kind>.records[]`
-or a custom `catalogs.<kind>.source` are exempt from unknown-id warnings for
-that kind.
+Validation reports carry `findings`. A finding with severity `error` is a
+structural problem that makes `valid` false; `warning` and `info` findings are
+advisory, such as an unknown catalog id in `narrative`, `design`, or a chart
+`type` reference (`opf/catalog-reference`) or a missing alt text. An id that a
+matching inline `catalogs.<kind>.records[]` entry defines is known, and a custom
+`catalogs.<kind>.source` exempts that kind's ids from unknown-id warnings
+unless the host loads the source's records and passes them as `catalogs`.
 
 ```ts
-const result = validatePresentation(deck);
-if (!result.valid) console.error(result.errors);
-for (const warning of result.warnings) console.warn(warning.path, warning.message);
+const report = validate(deck);
+if (!report.valid) console.error(report.findings.filter((finding) => finding.severity === "error"));
+for (const finding of report.findings) console.warn(finding.ruleId, finding.path, finding.message);
 ```
 
 Validate catalog records locally:
@@ -194,7 +199,7 @@ import { audiences, validateCatalogRecord } from "@openpresentation/opf";
 for (const record of audiences) {
   const result = validateCatalogRecord("audiences", record);
   if (!result.valid) {
-    console.error(result.errors);
+    console.error(result.findings);
   }
 }
 ```

package/dist/{catalogs-BnI7JKcn.d.ts → catalogs-D-yyQWCQ.d.ts}

@@ -1,4 +1,4 @@
-import { a as SchemaName } from './schemas-BSjlG8-R.js';
+import { S as SchemaName } from './schemas-DDpqAgyS.js';
 
 /**
  * Schema for audience records in the pptx.gallery library. Each record names an audience archetype (e.g. 'executive', 'engineering-team', 'investor') and carries seniority, technical-fluency, decision-power, and attention-budget hints used by AI-driven generation. Audiences are referenced from OPF documents via audience; the engine resolves the reference against catalogs.audiences (inline) → catalogs.audiences.source → the default catalog at https://www.pptx.gallery/audiences. The audience field also accepts free-form strings; this catalog is for engine-aware audience archetypes that carry generation hints.
@@ -54,7 +54,7 @@ interface Audience {
      */
     decisionPower?: ("informational" | "advisory" | "decision-maker");
     /**
-     * Realistic upper bound on this audience's focused attention for a single presentation, in minutes. Used as a hint when comparing against duration and the resolved narrative's durationRange.
+     * Realistic upper bound on this audience's focused attention for a single presentation, in minutes. Used as a hint when comparing against duration and the resolved narrative's duration range.
      */
     attentionBudgetMinutes?: number;
     /**
@@ -314,7 +314,7 @@ interface Theme {
     /**
      * Default slide size for this theme. Accepts the same preset values as design.dimensions.preset.
      */
-    dimensions?: ("16:9" | "4:3" | "16:10" | "letter" | "a4" | "widescreen" | "standard");
+    dimensions?: ("16:9" | "4:3" | "16:10" | "1:1" | "4:5" | "9:16" | "letter" | "a4" | "widescreen" | "standard");
     /**
      * Free-form labels for filtering and search.
      */
@@ -395,68 +395,9 @@ interface Layout {
      * Longer prose describing the layout structure and ideal use cases.
      */
     description?: string;
+    design?: DesignHints;
     /**
-     * Primary kind of content the layout holds. Drives pickers and AI placement decisions. Metric is the canonical numeric/KPI category; Number remains an accepted legacy label.
-     */
-    contentType?: ("Title" | "Text" | "List" | "Image" | "Number" | "Metric" | "Chart" | "Table" | "Code" | "Video" | "Quote" | "Timeline");
-    /**
-     * How many parallel content blocks the layout exposes ('2x' = two-column, '3x' = three-up, etc.).
-     */
-    contentMultiple?: ("None" | "1x" | "2x" | "3x" | "4x" | "5x" | "6x");
-    /**
-     * Default horizontal alignment of the content area.
-     */
-    contentAlignment?: ("None" | "Left" | "Center");
-    /**
-     * Whether the content area is rendered inside a visible box / card.
-     */
-    contentBox?: boolean;
-    /**
-     * For chart layouts, where the primary chart sits relative to the rest of the content.
-     */
-    contentTypeChartPrimary?: ("None" | "Top" | "Bottom" | "Left" | "Right");
-    /**
-     * For image layouts, how the image fills its slot.
-     */
-    contentTypeImageFill?: ("None" | "Crop" | "Fit");
-    /**
-     * For list layouts, how bullets are rendered.
-     */
-    contentTypeListBullet?: ("None" | "Character" | "Image");
-    /**
-     * For list layouts, whether each list item carries a heading.
-     */
-    contentTypeListHeading?: boolean;
-    /**
-     * Whether the layout includes a small slide-level tag / label region above or near the title.
-     */
-    slideTag?: boolean;
-    /**
-     * Whether the layout includes a slide title region.
-     */
-    slideTitle?: boolean;
-    /**
-     * Whether the layout includes a slide-level subtitle or supporting-description region. When placeholders is present, this is true exactly when the layout exposes a placeholder with type 'subtitle'.
-     */
-    slideSubtitle?: boolean;
-    /**
-     * Horizontal alignment of the slide title region.
-     */
-    slideTitleAlignment?: ("None" | "Left" | "Center");
-    /**
-     * Whether the layout includes a dedicated slide-level image region (separate from any content image).
-     */
-    slideImage?: boolean;
-    /**
-     * Where the slide-level image sits relative to the content.
-     */
-    slideImageAlignment?: ("None" | "Top" | "Bottom" | "Left" | "Right" | "Background");
-    /**
-     * Axis along which the layout's primary regions are arranged.
-     */
-    slideLayoutDirection?: ("None" | "Horizontal" | "Vertical");
-    /**
-     * Ordered regions the layout exposes. The engine fills 'title', 'subtitle', and 'tag' placeholders from Slide.title, Slide.subtitle, and Slide.tag. Other placeholders are content-kind hints for renderers and pickers. Slide content itself lives either in root payload fields or promoted region keys on Slide. Chrome — slide number, footer, date — is not included here; it is owned by Design.header / Design.footer.
+     * Ordered regions the layout exposes. This is the single source of truth for what the layout holds: the content kind, the number of body regions and whether it has a title, subtitle or tag are derived from it (layoutContent in @openpresentation/opf), never stored separately. The engine fills 'title', 'subtitle' and 'tag' placeholders from Slide.title, Slide.subtitle and Slide.tag. The other placeholders are content-kind regions that composition uses to size the body and that pickers use to match layouts. Slide content itself lives either in root payload fields or promoted region keys on Slide. Chrome (slide number, footer, date) is not included here; it is owned by Design.header / Design.footer.
      */
     placeholders?: Placeholder[];
     /**
@@ -485,16 +426,58 @@ interface Layout {
     [k: string]: unknown;
 }
 /**
- * A single region inside a slide layout. Title, subtitle, and tag placeholders bind to the corresponding Slide fields; other placeholders describe the intended content kind for that region. The array order in the surrounding 'placeholders' field preserves layout region order.
+ * The layout's design hints, with the same keys and values as the deck's design and a slide's design (a slide overrides exactly what its layout sets, by the same name). An absent key means the layout has no opinion. Every key is applied from the record as the lowest-precedence default, per key: the slide's design, then the deck's design, then this record's design, then the engine default, so a layout value nobody overrides is honored without copying it anywhere (a layout's composition.mode still ranks above contentDirection; slideImage.position is the fallback position of a slide image the layout reserves). Composition, the renderer and the PPTX exporter all read the one result.
+ */
+interface DesignHints {
+    /**
+     * Horizontal alignment of the title placeholder.
+     */
+    titleAlignment?: ("left" | "center" | "right");
+    /**
+     * Horizontal alignment of the body regions.
+     */
+    contentAlignment?: ("left" | "center" | "right");
+    /**
+     * Whether the body regions are drawn inside a visible card or surface.
+     */
+    contentBox?: boolean;
+    /**
+     * Axis along which parallel body content is arranged: 'vertical' is a column, 'horizontal' a row. Composition applies it when neither the slide nor this layout's composition sets a mode, below the slide's and the deck's design.contentDirection and above automatic selection.
+     */
+    contentDirection?: ("horizontal" | "vertical");
+    /**
+     * Where the primary chart sits relative to the other body content. Composition applies it below the slide's and the deck's design.chartPrimary, with the semantics described there.
+     */
+    chartPrimary?: ("none" | "top" | "bottom" | "left" | "right");
+    /**
+     * How images fill their region: 'crop' covers the region, 'fit' shows the whole image.
+     */
+    imageFill?: ("crop" | "fit");
+    /**
+     * Marker style of lists: 'character' draws the glyph, 'image' draws the deck's icon logo as a picture bullet.
+     */
+    listBullet?: ("character" | "image");
+    /**
+     * A slide-level image region the layout reserves, separate from any content image. Its presence is what lets a deck-wide design.slideImage apply to slides on this layout. The image itself comes from the slide or the deck design.
+     */
+    slideImage?: {
+        /**
+         * Where the slide-level image sits relative to the content. 'background' is a full-bleed image behind the content; the other positions give the image a band along that edge. Used when the slide's or deck's design.slideImage gives no position.
+         */
+        position: ("background" | "top" | "bottom" | "left" | "right");
+    };
+}
+/**
+ * A single region inside a slide layout. Title, subtitle, and tag placeholders bind to the corresponding Slide fields; every other placeholder describes the content kind that region holds. The array order in the surrounding 'placeholders' field preserves layout region order.
  *
  * This interface was referenced by `Layout`'s JSON-Schema
  * via the `definition` "Placeholder".
  */
 interface Placeholder {
     /**
-     * OPF placeholder kind. 'text' and 'list' are flexible textual content regions. 'metric' is a numeric/KPI content region filled by a metric payload, including its optional label, description, unit, delta, and trend. The named kinds describe a specific content role used by pickers, AI generation, and engine defaulting. 'picture' and legacy 'diagram' use image payloads; 'media' uses video. Quote and timeline use their corresponding payload fields.
+     * The content kind of the region. This is the one OPF content-kind vocabulary: the same words name a slide's payload fields (text, items, image, video, chart, table, code, metric, quote, timeline). 'title', 'subtitle' and 'tag' are the heading kinds and bind to Slide.title, Slide.subtitle and Slide.tag. 'text' holds text and bullets; 'list' holds items. 'image' is filled by an image payload and 'video' by a video payload. 'metric', 'quote', 'timeline', 'chart', 'table' and 'code' are filled by the payload of the same name; a metric region shows the metric payload with its optional label, description, unit, delta, trend and sentiment.
      */
-    type: ("title" | "subtitle" | "tag" | "text" | "metric" | "quote" | "timeline" | "list" | "chart" | "picture" | "table" | "media" | "diagram" | "code");
+    type: ("title" | "subtitle" | "tag" | "text" | "list" | "image" | "video" | "chart" | "table" | "code" | "metric" | "quote" | "timeline");
     [k: string]: unknown;
 }
 /**
@@ -538,7 +521,7 @@ interface Composition {
 }
 
 /**
- * Schema for chart-type records in the pptx.gallery catalog. The bundled catalog holds one record per chart type that Aspose.Slides officially supports (see mappings.renderers["aspose-slides"].chartType). Each record describes a named chart variant, its Open XML mapping, its series/category cardinality, the column structure of the underlying workbook, and a small sample dataset suitable for previews. Chart types are referenced from OPF chart content payloads; the engine resolves the reference against catalogs.chartTypes (inline) -> catalogs.chartTypes.source -> the default catalog at https://www.pptx.gallery/chart-types.
+ * Schema for chart-type records in the pptx.gallery catalog. The bundled catalog holds one record per chart type that Aspose.Slides officially supports (see mappings.renderers["aspose-slides"].chartType), plus the column-and-line combination 'combo' (mappings.openxml.composition "mixed"). Each record names a chart variant, its Open XML mapping, how many data series it expects and how pickers group it. Chart types are referenced from OPF chart content payloads; the engine resolves the reference against catalogs.chartTypes (inline) -> catalogs.chartTypes.source -> the default catalog at https://www.pptx.gallery/chart-types.
  */
 interface ChartType {
     /**
@@ -546,17 +529,13 @@ interface ChartType {
      */
     $schema: "https://openpresentation.org/schema/opf-chart-type/v1";
     /**
-     * Stable slug used by OPF documents to reference this chart type. Lowercase kebab-case. Chart type ids may start with a digit (e.g., '100pct-stacked-column', '3d-column') to mirror conventional chart naming.
+     * Stable slug used by OPF documents to reference this chart type (`chart.type`). Lowercase kebab-case. Chart type ids may start with a digit (e.g., '100pct-stacked-column', '3d-column') to mirror conventional chart naming.
      */
     id: string;
     /**
-     * Stable display/programmatic name for this chart type.
+     * Human-readable name of the chart type, as a chart picker shows it.
      */
     name: string;
-    /**
-     * Human-readable label shown in chart pickers.
-     */
-    label?: string;
     /**
      * One-sentence positioning: when to reach for this chart variant.
      */
@@ -568,7 +547,7 @@ interface ChartType {
     mappings: ChartTypeMappings;
     deprecation?: ChartTypeDeprecation;
     /**
-     * Top-level grouping in the chart picker (column, bar, line, area, pie, radar, etc.).
+     * Top-level grouping in the chart picker.
      */
     group?: string;
     /**
@@ -576,46 +555,13 @@ interface ChartType {
      */
     groupSort?: number;
     /**
-     * Shape of the underlying data: a flat series ('simple'), one with engine-side calculation ('calculated'), parent-child rows ('hierarchical'), or pre-normalized rows ('normalized').
+     * Shape of the underlying data: a flat series ('simple'), one with engine-side calculation ('calculated'), parent-child rows ('hierarchical'), or pre-normalized rows ('normalized'). The editor offers only 'simple' types as switch targets for a chart's existing data.
      */
     complexity?: ("simple" | "calculated" | "hierarchical" | "normalized");
     /**
-     * Number of data series this chart type expects.
+     * Number of data series this chart type expects: exactly that many, except that a stacked or percent-stacked type and a combination (composition 'mixed', such as combo) expect at least that many. The editor offers a type that expects more than one series only for data with a fitting number of value columns; a one-series type fits one value column, and column, bar, line, area and radar types fit any number.
      */
     series?: number;
-    /**
-     * Number of category labels this chart type expects on the primary axis.
-     */
-    categories?: number;
-    /**
-     * Number of series groups (axis bands) this chart type uses; >1 for combo or banded charts.
-     */
-    seriesGroups?: number;
-    /**
-     * Whether the chart type uses a secondary category axis.
-     */
-    useSecondaryCategories?: boolean;
-    /**
-     * A1 reference to the source range in the embedded workbook.
-     */
-    workbookRange?: string;
-    /**
-     * Column header names of the embedded workbook, in left-to-right order.
-     */
-    columns?: string[];
-    /**
-     * Per-column metadata describing the role and position of each column in the workbook source.
-     */
-    dataColumns?: ChartDataColumn[];
-    /**
-     * Optional auxiliary column names used by calculated or banded charts (e.g., 'Excellent', 'Good', 'Fair', 'Poor' for a bullet chart).
-     */
-    helperColumns?: string[];
-    sampleData?: ChartSampleData;
-    /**
-     * Source slide number in the original chart-gallery deck. Carried for traceability.
-     */
-    slideNumber?: number;
     /**
      * Free-form labels for filtering and search.
      */
@@ -646,7 +592,7 @@ interface ChartType {
      */
     [k: string]: {
         [k: string]: unknown;
-    } | "https://openpresentation.org/schema/opf-chart-type/v1" | string | ChartTypeMappings | ChartTypeDeprecation | number | "simple" | "calculated" | "hierarchical" | "normalized" | boolean | string[] | ChartDataColumn[] | ChartSampleData | {
+    } | "https://openpresentation.org/schema/opf-chart-type/v1" | string | ChartTypeMappings | ChartTypeDeprecation | number | "simple" | "calculated" | "hierarchical" | "normalized" | string[] | {
         /**
          * Main preview image (PNG/JPG). Used as the primary visual in picker UIs and previews of the record.
          */
@@ -668,7 +614,7 @@ interface ChartType {
 interface ChartTypeMappings {
     openxml: OpenXmlChartMapping;
     /**
-     * Optional renderer-specific mappings. Keys are renderer ids; values are intentionally opaque to OPF. The bundled catalog records the matching Aspose.Slides ChartType enumeration member under the "aspose-slides" key, e.g. {"aspose-slides": {"chartType": "StackedColumn"}}.
+     * Optional renderer-specific mappings. Keys are renderer ids; values are intentionally opaque to OPF. The bundled catalog records the matching Aspose.Slides ChartType enumeration member under the "aspose-slides" key, e.g. {"aspose-slides": {"chartType": "StackedColumn"}}; a mixed composition names the ChartType it starts from and the series type it switches series to, e.g. {"chartType": "ClusteredColumn", "lineSeriesType": "LineWithMarkers"}.
      */
     renderers?: {
         [k: string]: {
@@ -768,7 +714,7 @@ interface OpenXmlChartMapping1 {
     notes?: string;
 }
 /**
- * Present when this chart type is deprecated. Deprecated records stay resolvable so existing documents keep validating, but pickers and default listings exclude them, validators warn when a document references them, and they are removed in the release named by `removal`.
+ * Present when this chart type is deprecated. A deprecated record stays resolvable so existing documents keep validating, validators warn when a document references it, and pickers and generators should not offer it. The bundled default catalog holds no deprecated records; a publisher or an inline `catalogs.chartTypes.records` entry can still use the field.
  */
 interface ChartTypeDeprecation {
     /**
@@ -784,48 +730,9 @@ interface ChartTypeDeprecation {
      */
     removal?: string;
 }
-/**
- * One column of the embedded chart workbook, annotated with its role and grid position.
- *
- * This interface was referenced by `ChartType`'s JSON-Schema
- * via the `definition` "ChartDataColumn".
- */
-interface ChartDataColumn {
-    /**
-     * Column header name (e.g. 'Series 1', 'Value', 'Level1', 'Level2').
-     */
-    name: string;
-    /**
-     * Role this column plays: a category label (axis tick), a series (plotted values), or a helper (calculated/auxiliary).
-     */
-    role: ("categoryLabel" | "series" | "helper");
-    /**
-     * Cell value type for the column.
-     */
-    type: ("string" | "number");
-    /**
-     * Grid position of the column header in the source workbook, as 'row<N>_col<M>' (zero-indexed).
-     */
-    position?: string;
-    [k: string]: unknown;
-}
-/**
- * Inline sample dataset for previews and pickers.
- */
-interface ChartSampleData {
-    /**
-     * Header row labels. The first cell typically labels the series column; the rest are category labels.
-     */
-    headers: string[];
-    /**
-     * Two-dimensional sample data. Each row aligns by index with the headers — first cell is the row label, remaining cells are values.
-     */
-    rows: (string | number)[][];
-    [k: string]: unknown;
-}
 
 /**
- * Schema for narrative template files in the openpresentation.org catalog. Each template describes a named story arc (e.g. 'problem-solution', 'scqa') as an ordered list of beats. Templates are referenced from OPF documents via narrative — either as a bare id string (e.g. 'classic-story') or as an inline object whose shape matches this schema (sans '$schema').
+ * Schema for narrative template files in the openpresentation.org catalog. A narrative is a plan: a named story arc (e.g. 'problem-solution', 'scqa') as an ordered list of beats, each saying what its slide must do. A document points at one with the string 'narrative' (a catalog id, an HTTPS URL or a 'pkg:' reference) and links its slides to beats with 'slides[].beat'. A custom narrative is a record in 'catalogs.narratives.records'. Core validate warns about a 'slides[].beat' id the resolved narrative does not define (opf/unknown-beat) and about a root 'duration' outside this record's 'duration' range (opf/duration-outside-narrative), and reports a beat no slide references (opf/unused-beat).
  */
 interface Narrative {
     $schema: "https://openpresentation.org/schema/opf-narrative/v1";
@@ -867,12 +774,17 @@ interface Narrative {
      */
     audienceFit?: string[];
     /**
-     * Typical talk-length window this narrative suits.
+     * Typical talk length this narrative suits, as a range in minutes. A deck's own target is the root 'duration' (one number); core validate warns when that target lies outside this range, and when 'min' is greater than 'max'.
      */
-    durationRange?: {
-        minMinutes?: number;
-        maxMinutes?: number;
-        [k: string]: unknown;
+    duration?: {
+        /**
+         * Shortest talk length, in minutes, this narrative suits.
+         */
+        min?: number;
+        /**
+         * Longest talk length, in minutes, this narrative suits.
+         */
+        max?: number;
     };
     /**
      * Free-form labels for filtering and search, e.g. ['business', 'pitch', 'internal'].
@@ -905,7 +817,7 @@ interface Narrative {
     [k: string]: unknown;
 }
 /**
- * A single narrative beat — a labeled segment of the story arc with a specific dramatic purpose. Mirrors the NarrativeBeat definition in opf.schema.json so library entries and inline OPF beats are interchangeable.
+ * A single narrative beat — a labeled segment of the story arc with a specific dramatic purpose. One beat is one slide: 'type' is that slide's Slide.type and 'layout' is its Slide.layout, so a planner copies them straight into a skeleton deck. Split a heavy beat into several beats rather than giving it several slides.
  *
  * This interface was referenced by `Narrative`'s JSON-Schema
  * via the `definition` "Beat".
@@ -928,26 +840,22 @@ interface Beat {
      */
     instructions?: string;
     /**
-     * Optional explicit slide count for this beat. Defaults to 1 when omitted; values >1 are reserved for beats that intentionally span multiple slides. Prefer decomposing a heavy beat into multiple beats over setting a high slideCount. The validator emits a warning if the deck's actual count differs significantly.
-     */
-    slideCount?: number;
-    /**
-     * Default content kind for the beat's slide. Uses ContentPayload.type names to help engines choose a layout. The legacy shape value is retained for compatibility and requests an image representation; it is not a native ContentPayload type.
+     * Default content kind for the beat's slide: the same values as Slide.type. Helps engines and planners choose a layout when only the beat is known.
      */
-    slideType?: ("text" | "list" | "image" | "shape" | "chart" | "table" | "video" | "code" | "metric" | "quote" | "timeline");
+    type?: ("text" | "list" | "image" | "video" | "chart" | "table" | "code" | "metric" | "quote" | "timeline");
     /**
-     * Suggested layout id for the beat's opening slide, e.g. 'section-divider', 'title-slide', 'text-left'. Resolves the same way as Slide.layout — against catalogs.layouts and the default catalog at https://www.pptx.gallery/layouts.
+     * Suggested layout id for the beat's slide, e.g. 'section-divider', 'title-slide', 'text-left'. Resolves the same way as Slide.layout — against catalogs.layouts and the default catalog at https://www.pptx.gallery/layouts.
      */
-    layoutHint?: string;
+    layout?: string;
     /**
-     * Optional speaker or thinking cues attached to the beat. Surfaced in presenter notes.
+     * Optional speaker or thinking cues for the beat: questions the slide should answer. A planner or author turns them into the slide's notes; no engine copies them there on its own.
      */
     thoughtCues?: string[];
     [k: string]: unknown;
 }
 
 /**
- * Schema for social-platform records in the pptx.gallery library. Each record describes a single social-media platform — its base URL, profile-URL pattern, handle prefix, brand color, and themed icons. Records are referenced from OPF documents indirectly: the property keys of any Socials object (Organization.socials, Speaker.socials) match record ids, and engines use the catalog record's URL patterns and handle prefix to format and link the profile URL. The brand color and the themed icons are catalog metadata for authoring UIs: engines (opf-render, opf-pptx) render the profile URL, not icons or brand colors. The engine resolves references against catalogs.socialPlatforms (inline) → catalogs.socialPlatforms.source → the default catalog at https://www.pptx.gallery/social-platforms.
+ * Schema for social-platform records in the pptx.gallery library. Each record describes a single social-media platform — its base URL, profile-URL pattern, handle prefix, and brand color. Records are referenced from OPF documents indirectly: the property keys of any Socials object (Organization.socials, Speaker.socials) match record ids, and engines use the catalog record's URL patterns and handle prefix to format and link the profile URL. The brand color is catalog metadata for authoring UIs: engines (opf-render, opf-pptx) render the profile URL, not brand colors. The engine resolves references against catalogs.socialPlatforms (inline) → catalogs.socialPlatforms.source → the default catalog at https://www.pptx.gallery/social-platforms.
  */
 interface SocialPlatform {
     /**
@@ -1011,18 +919,6 @@ interface SocialPlatform {
      * Brand color (hex) for branded icon chips, link styling, or section accents in authoring UIs. Catalog metadata: engines do not draw it.
      */
     brandColor?: string;
-    /**
-     * Default icon source. Accepts an HTTPS URL, data URI, relative path, or asset reference. Used as the fallback when a themed (Light/Dark) variant isn't set. Catalog metadata for authoring UIs: engines do not draw icons.
-     */
-    icon?: string;
-    /**
-     * Light-colored icon variant intended for authoring UIs that draw the icon on dark backgrounds (engines do not draw icons).
-     */
-    iconLight?: string;
-    /**
-     * Dark-colored icon variant intended for authoring UIs that draw the icon on light backgrounds (engines do not draw icons).
-     */
-    iconDark?: string;
     /**
      * Free-form labels for filtering and search.
      */
@@ -1259,7 +1155,7 @@ interface ColorScheme {
 }
 
 /**
- * Schema for font-scheme records in the pptx.gallery library. Each scheme pairs a major (heading) and minor (body) font family in the OOXML majorFont/minorFont sense, scoped to a target app (PowerPoint or Google Slides) and a language family (Latin, East Asian, or Complex Script). Font schemes are referenced from OPF documents via design.fontScheme or design.fontScheme.id; the engine resolves the reference against catalogs.fontSchemes (inline) → catalogs.fontSchemes.source → the default catalog at https://www.pptx.gallery/font-schemes. Role overrides on design.fontScheme (heading, body, accent, code) take precedence over the resolved scheme.
+ * Schema for font-scheme records in the pptx.gallery library. Each scheme pairs a major (heading) and minor (body) font family in the OOXML majorFont/minorFont sense, scoped to a target app (powerpoint or google-slides) and a language family (Latin, East Asian, or Complex Script). Font schemes are referenced from OPF documents via design.fontScheme or design.fontScheme.id; the engine resolves the reference against catalogs.fontSchemes (inline) → catalogs.fontSchemes.source → the default catalog at https://www.pptx.gallery/font-schemes. Role overrides on design.fontScheme (heading, body, accent, code), each a font family name, take precedence over the resolved scheme.
  */
 interface FontScheme {
     /**
@@ -1300,27 +1196,9 @@ interface FontScheme {
      */
     minor: string;
     /**
-     * Optional monospaced font for code blocks and inline code. It has the same shape as the OPF FontScheme 'code' role, so a record and an inline design.fontScheme override are interchangeable. OOXML has no code slot, so exporters write this family on code runs. When neither design.fontScheme nor the resolved record defines 'code', engines fall back to Roboto Mono.
+     * Optional monospaced font family name for code blocks and for inline code runs (TextRun.code). It has the same shape as the OPF FontScheme 'code' role, so a record and an inline design.fontScheme override are interchangeable. OOXML has no code slot, so exporters write this family on code runs. When neither design.fontScheme nor the resolved record defines 'code', engines fall back to Roboto Mono.
      */
-    code?: {
-        /**
-         * Monospaced font family name.
-         */
-        family: string;
-        /**
-         * Numeric font weight (e.g., 400 for regular, 700 for bold).
-         */
-        weight?: number;
-        /**
-         * Font style.
-         */
-        style?: ("normal" | "italic");
-        /**
-         * Letter spacing (tracking) in ems.
-         */
-        letterSpacing?: number;
-        [k: string]: unknown;
-    };
+    code?: string;
     /**
      * East Asian script fonts. Maps to the OOXML a:ea element of majorFont (major) and minorFont (minor), and to run-level a:ea. When set, they fill the eastAsian slot for every language; when omitted, the slot comes from this scheme's own major/minor when languageFamily is 'ea' and the scheme's languages list is empty or names the presentation language, then from the presentation language's font scheme for East Asian languages, and otherwise from the latin (major/minor) families. A missing 'major' or 'minor' falls back to the other.
      */
@@ -1352,15 +1230,15 @@ interface FontScheme {
      */
     type?: ("sans-serif" | "serif" | "monospace");
     /**
-     * Target application this font pairing is intended for.
+     * Target application this font pairing is intended for. Metadata for pickers and catalog filters: no engine changes its output by it.
      */
-    app?: ("PowerPoint" | "Google Slides");
+    app?: ("powerpoint" | "google-slides");
     /**
-     * OOXML font-language family this scheme is intended for: 'latin' for Latin-script content, 'ea' for East Asian scripts, 'cs' for Complex Scripts. As the design font scheme, an 'ea' or 'cs' scheme also fills that script slot with its own major/minor families when its languages list is empty or names the presentation language.
+     * Font-language family this scheme is intended for: 'latin' for Latin-script content, 'ea' (or 'eastAsian', the same value) for East Asian scripts, 'cs' (or 'complexScript', the same value) for Complex Scripts. The long names match the 'eastAsian' and 'complexScript' slot keys; the short names match the OOXML a:ea and a:cs elements; core reads both spellings as one value. As the design font scheme, an 'ea'/'eastAsian' or 'cs'/'complexScript' scheme also fills that script slot with its own major/minor families when its languages list is empty or names the presentation language.
      */
-    languageFamily?: ("latin" | "ea" | "cs");
+    languageFamily?: ("latin" | "ea" | "cs" | "eastAsian" | "complexScript");
     /**
-     * Optional list of human-readable language names this scheme is curated for. Useful for picker UIs that group fonts by language coverage.
+     * Optional list of languages catalog ids (see the languages catalog, https://www.pptx.gallery/languages) this scheme is curated for. Useful for picker UIs that group fonts by language coverage. As the design font scheme, an 'ea' or 'cs' scheme fills its script slot only when this list is empty or names the presentation language by id.
      */
     languages?: string[];
     /**
@@ -1462,4 +1340,4 @@ interface CatalogEntry {
 }
 declare const catalogEntries: readonly CatalogEntry[];
 
-export { type Audience as A, type CatalogKind as C, type FontScheme as F, type Language as L, type Narrative as N, type Purpose as P, type SocialPlatform as S, type Theme as T, type CatalogEntry as a, type CatalogIndex as b, type CatalogIndexRecord as c, type CatalogRecord as d, type ChartType as e, type ColorScheme as f, type Layout as g, type Tone as h, audiences as i, catalogEntries as j, catalogIndexes as k, catalogKinds as l, catalogSchemaNames as m, catalogs as n, chartTypes as o, colorSchemes as p, fontSchemes as q, languages as r, layouts as s, narratives as t, purposes as u, socialPlatforms as v, themes as w, tones as x };
+export { type Audience as A, type CatalogKind as C, type FontScheme as F, type Language as L, type Narrative as N, type Purpose as P, type SocialPlatform as S, type Theme as T, type ChartType as a, type ColorScheme as b, type Layout as c, type Tone as d, type CatalogEntry as e, type CatalogIndex as f, type CatalogIndexRecord as g, type CatalogRecord as h, audiences as i, catalogEntries as j, catalogIndexes as k, catalogKinds as l, catalogSchemaNames as m, catalogs as n, chartTypes as o, colorSchemes as p, fontSchemes as q, languages as r, layouts as s, narratives as t, purposes as u, socialPlatforms as v, themes as w, tones as x };

package/dist/catalogs.d.ts

@@ -1,2 +1,2 @@
-export { a as CatalogEntry, b as CatalogIndex, c as CatalogIndexRecord, C as CatalogKind, d as CatalogRecord, i as audiences, j as catalogEntries, k as catalogIndexes, l as catalogKinds, m as catalogSchemaNames, n as catalogs, o as chartTypes, p as colorSchemes, q as fontSchemes, r as languages, s as layouts, t as narratives, u as purposes, v as socialPlatforms, w as themes, x as tones } from './catalogs-BnI7JKcn.js';
-import './schemas-BSjlG8-R.js';
+export { e as CatalogEntry, f as CatalogIndex, g as CatalogIndexRecord, C as CatalogKind, h as CatalogRecord, i as audiences, j as catalogEntries, k as catalogIndexes, l as catalogKinds, m as catalogSchemaNames, n as catalogs, o as chartTypes, p as colorSchemes, q as fontSchemes, r as languages, s as layouts, t as narratives, u as purposes, v as socialPlatforms, w as themes, x as tones } from './catalogs-D-yyQWCQ.js';
+import './schemas-DDpqAgyS.js';

package/dist/catalogs.js

@@ -1,2 +1,2 @@
 import './chunk-S5W34SIJ.js';
-export { audiences, catalogEntries, catalogIndexes, catalogKinds, catalogSchemaNames, catalogs, chartTypes, colorSchemes, fontSchemes, languages, layouts, narratives, purposes, socialPlatforms, themes, tones } from './chunk-E34DJ5LL.js';
+export { audiences, catalogEntries, catalogIndexes, catalogKinds, catalogSchemaNames, catalogs, chartTypes, colorSchemes, fontSchemes, languages, layouts, narratives, purposes, socialPlatforms, themes, tones } from './chunk-XOZ4KMSR.js';